Ma doctrine d'artisan développeur

Journaux liées à cette note :

Le 6 novembre 2024, j'ai publié la note "Le support des variables d'environments de Mise est limité, je continue à utiliser direnv".

L'issue indiquée dans cette note a été cloturée il y a 3 jours : Use mise tools in env template · Issue #1982.

Voici le contenu de changement de la documentation : https://github.com/jdx/mise/pull/3598/files#diff-e8cfa8083d0343d5a04e010a9348083f7b64035c407faa971074c6f0e8d0d940

Ce qui signifie que je vais pouvoir maintenant utiliser terraform installé via Mise dans le fichier .envrc :

[env]
_.source = { value = "./.envrc.sh", tools = true }

[tools]
terraform="1.9.8"

Après avoir installé la dernière version de Mise, j'ai testé cette configuration dans repository suivant : install-and-configure-mise-skeleton.

Le fichier .envrc suivant a fonctionné :

export HELLO_WORLD=foo3
export NOW=$(date)
export TERRAFORM_VERSION=$(terraform --version | head -n1)

Exemple :

$ mise trust
$ echo $TERRAFORM_VERSION
Terraform v1.9.8

Je n'ai pas trouvé de commande Mise pour recharger les variables d'environnement du dossier courant, sans quitter le dossier. Avec direnv, pour effectuer un rechargement je lançais : direnv allow.

À la place, j'ai trouvé la méthode suivante :

$ source .envrc

Je pense pouvoir maintenant remplacer Direnv par Mise 🤞.

J'utilise la fonctionnalité Docker volume mounts dans tous mes projets depuis septembre 2015.

Généralement, sous la forme suivante :

services:
  postgres:
    image: postgres:17
    ...
	volumes:
      - ./volumes/postgres/:/var/lib/postgresql/data/

D'après mes recherches, la fonctionnalité volumes mounts a été introduite dans la version 0.5.0 en juillet 2013.

À cette époque, je crois me souvenir que Docker permettait aussi de créer des volumes anonymes. Je n'ai jamais apprécié les volumes anonymes, car lorsqu'un conteneur était supprimé, il devenait compliqué de retrouver le volume associé.
À cette époque, Docker était nouveau et j'avais très peur de perdre des données, par exemple, les volumes d'une instance PostgreSQL.

J'ai donc décidé qu'il était préférable de renoncer aux volumes anonymes et d'opter systématiquement pour des volume mounts.

Ensuite, peut-être en janvier 2016, Docker a introduit les named volumes, qui permettent de créer des volumes avec des noms précis, par exemple :

services:
  postgres:
    image: postgres:17
    ...
	volumes:
      - postgres:/var/lib/postgresql/data/

volumes:
  postgres:
    name: postgres

$ docker volume ls
DRIVER    VOLUME NAME
local     postgres

Ce volume est physiquement stocké dans le dossier /var/lib/docker/volumes/postgres/_data.

Depuis, j'ai toujours préféré les volumes mounts aux named volumes pour les raisons pratiques suivantes :

Travaillant souvent sur plusieurs projets, j'utilise les volume mounts pour éviter les collisions. Lorsque j'ai essayé les named volumes, une question s'est posée : quel nom attribuer aux volumes PostgreSQL ? « postgres » ? Mais alors, quel nom donner au volume PostgreSQL dans le projet B ? Avec les volume mounts, ce problème ne se pose pas.
J'apprécie de savoir qu'en supprimant un projet avec rm -rf ~/git/github.com/stephan-klein/foobar/, cette commande effacera non seulement l'intégralité du projet, mais également ses volumes Docker.
Avec les mounted volume, je peux facilement consulter le contenu des volumes. Je n'ai pas besoin d'utiliser docker volume inspect pour trouver le chemin du volume.

La stratégie que j'ai choisie basée sur volumes mounts a quelques inconvénients :

Le owner du dossier volumes/, situé dans le répertoire du projet, est root. Cela entraîne fréquemment des problèmes de permissions, par exemple lors de l'exécution des scripts de linter dans le dossier du projet. Pour supprimer le projet, je dois donc utiliser sudo. Je précise que ce problème n'existe pas sous MacOS. Je pense que ce problème pourrait être contourné sous Linux en utilisant podman.
La commande docker compose down -v ne détruit pas les volumes.

Je suis pleinement conscient que ma méthode basée sur les volume mounts est minoritaire. En revanche, j'observe qu'une grande majorité des développeurs privilégie l'utilisation des named volumes.

Par exemple, cet été, un collègue a repris l'un de mes projets, et l'une des premières choses qu'il a faites a été de migrer ma configuration de volume mounts vers des named volumes pour résoudre un problème de permissions lié à Prettier, eslint ou Jest. En effet, la fonctionnalité ignore de ces outils ne fonctionne pas si NodeJS n'a pas les droits d'accès à un dossier du projet 😔.

Aujourd'hui, je me suis lancé dans la recherche d'une solution me permettant d'utiliser des named volumes tout en évitant les problèmes de collision entre projets.

Je pense que j'ai trouvé une solution satisfaisante 🙂.

Je l'ai décrite et testée dans le repository docker-named-volume-playground.

Ce repository d'exemple contient 2 projets distincts, nommés project_a et project_b.
J'ai instancié deux fois chacun de ces projets. Voici la liste des dossiers :

$ tree
.
├── project_a_instance_1
│   ├── docker-compose.yml
│   └── .envrc
├── project_a_instance_2
│   ├── docker-compose.yml
│   └── .envrc
├── project_b_instance_1
│   ├── docker-compose.yml
│   └── .envrc
├── project_b_instance_2
│   ├── docker-compose.yml
│   └── .envrc
└── README.md

Ce repository illustre l'organisation de plusieurs instances de différents projets sur la workstation du développeur.
Il ne doit pas être utilisé tel quel comme base pour un projet.
Par exemple, le "vrai" repository du projet projet_a se limiterait aux fichiers suivants : docker-compose.yml et .envrc.

Voici le contenu d'un de ces fichiers .envrc :

export PROJECT_NAME="project_a"
export INSTANCE_ID=$(pwd | shasum -a 1 | awk '{print $1}' | cut -c 1-12) # Used to define docker volume path
export COMPOSE_PROJECT_NAME=${PROJECT_NAME}_${INSTANCE_ID}

L'astuce que j'utilise est au niveau de INSTANCE_ID. Cet identifiant est généré de telle manière qu'il soit unique pour chaque instance de projet installée sur la workstation du développeur.
J'ai choisi de générer cet identifiant à partir du chemin complet vers le dossier de l'instance, je le passe dans la commande shasum et je garde les 12 premiers caractères.

J'utilise ensuite la valeur de COMPOSE_PROJECT_NAME dans le docker-compose.yml pour nommer le named volume :

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: postgres
      POSTGRES_DB: postgres
      POSTGRES_PASSWORD: password
    ports:
      - 5432
    volumes:
      - postgres:/var/lib/postgresql/data/
    healthcheck:
      test: ["CMD", "sh", "-c", "pg_isready -U $$POSTGRES_USER -h $$(hostname -i)"]
      interval: 10s
      start_period: 30s

volumes:
  postgres:
     name: ${COMPOSE_PROJECT_NAME}_postgres

Exemples de valeurs générées pour l'instance installée dans /home/stephane/git/github.com/stephane-klein/docker-named-volume-playground/project_a_instance_1 :

INSTANCE_ID=d4cfab7403e2
COMPOSE_PROJECT_NAME=project_a_d4cfab7403e2
Nom du container postgresql : project_a_d4cfab7403e2-postgres-1
Nom du volume postgresql : project_a_a04e7305aa09_postgres

Conclusion

Cette méthode me permet de suivre une pratique plus mainstream — utiliser les named volumes Docker — tout en évitant la collision des noms de volumes.

Je suis conscient que ce billet est un peu long pour expliquer quelque chose de simple, mais je tenais à partager l'historique de ma démarche.

Je pense que je vais dorénavant utiliser cette méthode pour tous mes nouveaux projets.

20224-12-10 11h27 : Je tiens à préciser qu'avec la configuration suivante :

services:
  postgres:
    image: postgres:17
    ...
	volumes:
      - postgres:/var/lib/postgresql/data/

volumes:
  postgres:

Quand le nom du volume postgres n'est pas défini, docker-compose le nomme sous la forme ${COMPOSE_PROJECT_NAME}_postgres. Si le projet est stocké dans le dossier foobar, alors le volume sera nommé foobar_postgres.

$ docker volume ls
DRIVER    VOLUME NAME
local     foobar_postgres

Je viens de rencontrer l'outil envdir (à ne pas confondre avec direnv) et son modèle de stockage de variables d'environnement, que je trouve très surprenant !

direnv ou dotenv utilisent de simples fichiers texte pour stocker les variables d'environnements, par exemple :

export POSTGRES_URL="postgres://postgres:password@localhost:5432/postgres"
export SMTP_HOST="127.0.0.1"
export SMTP_PORT="1025"
export MAIL_FROM="noreply@example.com"

Contrairement à ces deux outils, pour définir ces quatre variables, le modèle de stockage de envdir nécessite la création de 4 fichiers :

$ tree .
.
├── MAIL_FROM
├── POSTGRES_URL
├── SMTP_HOST
└── SMTP_PORT

1 directory, 4 files

$ cat POSTGRES_URL
postgres://postgres:password@localhost:5432/postgres
$ cat SMTP_HOST
127.0.0.1
$ cat SMTP_PORT
1025
$ cat MAIL_FROM
127.0.0.1

Je trouve ce modèle fort peu pratique. Contrairement à un simple fichier unique, le modèle de envdir présente certaines limitations :

Organisation : il ne permet pas de structurer librement l'ordre ou de regrouper visuellement les variables.
Lisibilité : l'ensemble de la configuration est plus difficile à visualiser d'un seul coup d'œil.
Manipulation : copier ou coller son contenu n'est pas aussi direct qu'avec un fichier texte.
Documentation : les commentaires ne peuvent pas être inclus pour expliquer les variables.
Rapidité : la saisie ou la modification de plusieurs variables demande plus de temps, chaque variable étant dans un fichier distinct.

J'ai été particulièrement intrigué par le choix fait par l'auteur de envdir. Sa décision semble vraiment surprenante.

envdir fait partie du projet daemontools, créé en 1990. Ainsi, il est bien plus ancien que dotenv, qui a été lancé autour de 2010, et direnv, qui date de 2014.

Si je me remets dans le contexte des années 1990, je pense que le modèle de envdir a été avant tout motivé par une simplicité d'implémentation plutôt que d'utilisation. En effet, il est plus facile de lister les fichiers d'un répertoire et de charger leur contenu que de développer un parser de fichiers.

Je pense qu'en 2024, envdir n'a plus sa place dans un environnement informatique moderne. Je recommande vivement de le remplacer par des solutions plus récentes, comme devenv ou direnv.

Personnellement, j'utilise direnv dans tous mes projets.

La fonctionnalité "Activité" de GitLab me manque dans GitHub.

Voici trois exemples concrets de fonctionnement de cette fonctionnalité, dans trois contextes différents.

Le premier, dans le projet GNOME Shell :

Le second, dans le groupe Wayland : https://gitlab.freedesktop.org/groups/wayland/-/activity

Et le troisième, pour l'utilisateur Lucas Stach: https://gitlab.freedesktop.org/users/lynxeye/activity

Je trouve cette fonctionnalité très utile quand on travaille sur un projet. Elle permet d'avoir une vue d'ensemble de ce qui s'est passé sur un projet sur une période. Elle vient en complément de l'historique Git qui est limité aux changements effectués sur le code source.

Dans certaines situations, je sais qu'un collègue travaille sur un sujet qui me concerne et la fonctionnalité "Activité" me permet de mieux comprendre où il en est, de suivre facilement ce qu'il fait.

Cette fonctionnalité "Activité" permet de pratiquer la stigmergie.

J'utilise aussi cette fonctionnalité lors de la rédaction d'un rapport d'activité ou d'un message de Daily Scrum. Elle m'aide à retrouver précisément ce que j'ai fait dernièrement.

Je trouve la page "Contribution activity" d'un user GitHub limité, par exemple, elle ne contient pas l'historique des commentaires.

Même chose au niveau d'un projet, dans la page "Pulse", par exemple : https://github.com/sveltejs/kit/pulse.

Je viens de regarder du côté de Codeberg / Forgejo : <https://codeberg.org/forgejo/forgejo/activity. Même constat que pour GitHub, les informations sont très réduites.

Depuis des années, j'hésite toujours entre get et fetch lors du naming de fonctions.

Je viens de demander à ChatGPT la différence entre ces deux verbes et quand est-ce qu'il est préférable d'utiliser l'un ou l'autre.

Voici sa réponse :

Pour get :

Signification : Indique une opération simple pour récupérer ou accéder à des données.

Contexte d'utilisation :

Utilisé pour des accès rapides et directs à des données qui sont déjà disponibles localement (en mémoire, en cache, etc.).

Souvent employé dans des fonctions "getter" ou des méthodes utilitaires simples.

Pour fetch :

Signification : Suggère une opération potentiellement asynchrone ou coûteuse, comme récupérer des données d'une source externe.

Contexte d'utilisation :

Lorsqu'une action supplémentaire est requise pour obtenir les données, comme un appel réseau ou une requête vers une API.

Implique souvent un effort ou une complexité plus grande que get.

J'ai essayé d'obtenir plus de ressources concernant cette déclaration.

J'ai trouvé ceci :

Ma recheche "[naming-conventions] fetch get" sur StackOverflow:
- naming conventions - Method names for getting data

Example: fetch implies that some entity needs to go and get something that is remote and bring it back. Dogs fetch a stick, and retrieve is a synonym for fetch with the added semantic that you may have had possession of the thing prior as well. get is a synonym for obtain as well which implies that you have sole possession of something and no one else can acquire it simultaneously.

source

Ma recherche "fetch get" sur English Language and Usage Stack Exchange :
- word choice - Fetch or Get from system?
Sur MDN Web Docs, j'ai effectué des recherches de fonctions qui commencent par get ou fetch. Je constate que le verbe fetch est utilisé lorsque la fonction va chercher des données sur le réseau.

Suite à cette étude, j'ai décidé d'utiliser fetch plutôt que get pour toutes les fonctions allant chercher des données en dehors du "processus local". Quelques exemples :

Utilisation de fetch pour nommer une fonction javascript frontend ou backend, qui effectue des requêtes REST ou GraphQL.
Utilisation de get pour nommer une fonction PL/pgSQL qui effectue uniquement des requêtes SQL sur la base de données locale (pas de requêtes vers des Foreign Data (PostgreSQL)). Ici "locale" signifie que l'instance qui exécute la fonction PL/pgSQL est la même que celle qui contient les tables requêtées (voir cet échange).

Je découvre une nouvelle limitation de Hasura par rapport à PostGraphile.

Hasura permet d'exécuter des fonctions PostgreSQL seulement si leur type de retour est une table. De plus, cette table doit être tracked par Hasura.

Return type: MUST be SETOF <table-name> OR <table-name> where <table-name> is already tracked.

Return type workaround: If the required SETOF table doesn't already exist or your function needs to return a custom type i.e. row set, you can create and track an empty table with the required schema to support the function.

-- from

D'autre part, Hasura doit avoir des permissions d'accès à cette table utilisée en retour de fonction.

Par exemple, Hasura ne supporte pas ce type de configuration :

REVOKE ALL PRIVILEGES ON TABLE foobar FROM hasurauser;

CREATE FUNCTION myfunction() RETURNS SETOF foobar
LANGUAGE sql VOLATILE SECURITY DEFINER
AS $$
     SELECT * FROM foobar
$$;

Cette limitation, parmi d'autres, renforce ma préférence pour PostGraphile plutôt que Hasura dans un contexte d'utilisation avec PostgreSQL — PostGraphile supporte uniquement PostgreSQL.

J'ai décidé d'utiliser la fonctionnalité "mise env._source" pendant quelques semaines pour me faire une opinion.

-- (from)

J'ai déjà rencontré un problème : il n'est pas possible de lancer des outils installés via Mise dans un script lancé par _.source.

Voici un exemple, j'ai ce fichier .envrc.sh :

export SERVER1_IP=$(terraform output --json | jq -r '.server1_public_ip | .value')

Terraform est installé avec Mise :

[env]
_.source = "./.envrc.sh"

[tools]
terraform="1.9.8"

Quand je lance mise set, j'ai cette erreur :

$ mise set
.envrc.sh: line 6: terraform: command not found

J'ai trouvé une issue pour traiter cette limitation : "Use mise tools in env template".

En attendant que cette issue soit implémentée, j'ai décidé de continuer d'utiliser direnv.

2024-12-19 : suite à la cloture de l'issue indiquée dans cette note, j'ai publié la note Je pense maintenant pouvoir remplacer Direnv par Mise 🤞.

Depuis avril 2019, j'utilise direnv dans pratiquement tous mes projets de développement informatique.

Ce matin je me suis demandé si avec les nouvelles fonctionnalités de gestion des variables d'environnement de Mise, je pouvais simplifier mes development kit 🤔.

Comme vous pouvez le voir dans install-and-configure-direnv-with-mise-skeleton, actuellement mes development kit contiennent deux étapes de modifications de .bash_profile ou .zshrc. Exemple avec Zsh :

Une étape pour configurer Mise :

$ echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
$ source ~/.zsrhrc

Seconde étape pour configurer direnv :

$ echo -e "\neval \"\$(direnv hook zsh)\"" >> ~/.zshrc
$ source ~/.zsrhrc

Voici la version simplifiée de ce skeleton basé sur "mise env._source", avec une étape de configuration en moins :

https://github.com/stephane-klein/install-and-configure-mise-skeleton

Voici le contenu du fichier .mise.toml :

[env]
_.source = "./.envrc.sh"

et le contenu de .envrc.sh :

export HELLO_WORLD=foo

J'ai fait le choix de nommer ce fichier .envrc.sh plutôt que .envrc afin d'éviter des problèmes de compatibilité pour les utilisateurs qui ont direnv installé.

J'ai vérifié que les variables d'environnements "parents" sont bien conservées en cas de changement de variable d'environnement par Mise dans un sous dossier.

#JeMeDemande si je vais rencontrer des régressions par rapport à direnv 🤔.

J'ai décidé d'utiliser la fonctionnalité "mise env._source" pendant quelques semaines pour me faire une opinion.

Update : voir 2024-11-06_2109.

Dans cette note, je souhaite expliquer pourquoi j'utilise et j'aime utiliser direnv.

Je suis toujours en train d'essayer de créer des development kit me permettant de travailler dans un environnements de développement toujours plus agréable.

J'ai découvert direnv en 2017 et j'ai commencé à l'utiliser dans un projet en avril 2019.

direnv s'utilise dans un shell, il charge et décharge automatiquement les variables d'environnement spécifiées dans un fichier .envrc lorsqu'on entre et quitte un répertoire.

Exemple :

Voici les use cases listées sur le site officiel de direnv :

Load 12factor apps environment variables

Create per-project isolated development environments

Load secrets for deployment

Voici quelques exemples concrets de mon utilisation de direnv :

chargement automatique des paramètres de configuration et secret pour :
- la cli de Scaleway
- terraform
- Grizzly

source .secret

export SCW_DEFAULT_ORGANIZATION_ID="...." # Get it, in https://console.scaleway.com/organization/settings
export SCW_ACCESS_KEY="..."

# This variable environments are used by Grafana Grizzly
export GRAFANA_URL=http://grafana.$(terraform output --json | jq -r '.server3_public_ip | .value').nip.io
export GRAFANA_USER=admin
export GRAFANA_TOKEN=password

dans un projet Javascript :

export POSTGRES_ADMIN_URL="postgres://postgres:password@localhost:5432/myapp"
export POSTGRES_URL="postgres://webapp:password@localhost:5432/myapp"
export SMTP_HOST="127.0.0.1"
export SMTP_PORT="1025"
export SECRET="secret"
export APP_HOSTNAME="localhost"
export MAIL_FROM="noreply@example.com"

Les fichiers .envrc sont des scripts shell, il est possible comme dans l'exemple au-dessus, d'utiliser source .secret pour charger un autre fichier.

Je versionne toujours le fichier .envrc, tandis que j'ignore (.gitignore) les fichiers .secret contenant des informations sensibles qui ne doivent pas être publiés dans le repository git.

Après avoir installé un development kit, j'indique à l'utilisateur les instructions à suivre pour installer les éléments de base du projet, comme Mise, Docker…, et la mise en place des secrets.

Mon objectif est ensuite de permettre à l'utilisateur de l'environnement de développement d'interagir avec des « scripts helpers » sans nécessiter de configuration préalable, simplement en entrant ou sortant des dossiers. Les dossiers sont utilisés comme « workspace contexte ».

Voir aussi : development kit skeleton d'installation de direnv

Suite à quelques cherches, j'ai décidé d'utiliser "commander" plutôt que "yargs" dans sklein-pkm-engine : lien vers le commit.

Je trouve cette librairie minimaliste :

program
  .option('--dry', 'Run in dry mode')
  .parse();

console.log(program.opts());

Résultat de "commander vs inquirer vs meow vs yargs" :